.\" SPDX-License-Identifier: CC-BY-SA-4.0 or-later
.\" SPDX-FileCopyrightText: 2025 grommunio GmbH
.TH zcore 8gx "" "Gromox" "Gromox admin reference"
.SH Name
zcore \(em Bridge for PHP-MAPI requests
.SH Synopsis
\fBzcore\fP [\fB\-c\fP \fIconfig\fP]
.SH Description
zcore is a bridge process (proxy) between PHP-MAPI and the Information Store
(see manpages mapi(4gx) and exmdb_provider(4gx), respectively). It
listens on /run/gromox/zcore.sock (hardcoded) for zcore RPCs, a Gromox-specific
protocol and issues exmdb RPCs to exmdb_provider(4gx). As exmdb_provider connections
have no state to speak of, zcore is the process that defines the logins sessions.
zcore needs to run on the same server as the program that uses the PHP-MAPI
functions.
.SH Options
.TP
\fB\-c\fP \fIconfig\fP
Read configuration directives from the given file. If this option is not
specified, /etc/gromox/zcore.cfg will be read if it exists.
.TP
\fB\-\-version\fP
Output version information and exit.
.TP
\fB\-?\fP
Display option summary.
.PP
All time-based command-line options and configuration file directives are
subject to the syntax described in gromox(7), section "Duration
specifications".
.SH Configuration directives (gromox.cfg)
The following directives are recognized when reading from
/etc/gromox/gromox.cfg, or when the \fB\-c\fP option is used to specify a
custom file:
.TP
\fBdaemons_fd_limit\fP
In gromox-zcore, this is treated as an alias for zcore_fd_limit.
.TP
\fBoutgoing_smtp_url\fP
See gromox.cfg(5):outgoing_smtp_url.
.TP
\fBzcore_fd_limit\fP
Request that the file descriptor table be at least this large. The magic value
0 indicates that the system default hard limit (rlim_max, cf. setrlimit(2))
should be used.
.br
Default: \fI0\fP
.SH Configuration directives (zcore.cfg)
The following directives are recognized when reading from /etc/gromox/zcore.cfg,
or when the \fB\-c\fP option is used to specify a custom file:
.TP
\fBaddress_cache_interval\fP
Default: \fI5 minutes\fP
.TP
\fBaddress_table_size\fP
Default: \fI3000\fP
.TP
\fBconfig_file_path\fP
Colon-separated list of directories which will be scanned when locating further
configuration files, especially those used by subcomponent instances. (For
example, mysql_adaptor(4gx) would be directed to look at
/etc/gromox/zcore/mysql_adaptor.cfg before /etc/gromox/mysql_adaptor.cfg.)
.br
Default: \fI/etc/gromox/zcore:/etc/gromox\fP
.TP
\fBdata_file_path\fP
Colon-separated list of directories which will be scanned when locating data
files.
.br
Default: \fI/usr/share/gromox/zcore\fP
.TP
\fBdefault_charset\fP
Default: \fIutf-8\fP
.TP
\fBhost_id\fP
A unique identifier for this system. It is used for the HELO line of outgoing
SMTP connections, and as an unused identifier within muidStoreWrap entryids.
The identifier should only use characters allowed for hostnames.
.br
Default: (system hostname)
.TP
\fBmailbox_ping_interval\fP
Default: \fI5 minutes\fP
.TP
\fBmail_max_length\fP
Default: \fI64M\fP
.TP
\fBmax_ext_rule_length\fP
Default: \fI510K\fP
.TP
\fBmax_rcpt_num\fP
The maximum number of recipients that an e-mail is allowed to have.
.br
Default: \fI256\fP
.TP
\fBnotify_stub_threads_num\fP
For every exmdb server in exmdb_list.txt, establish and keep this many number
of outbound connections for receiving notification RPCs.
.br
Default: \fI10\fP
.TP
\fBrpc_proxy_connection_num\fP
For every exmdb server in exmdb_list.txt, establish and keep this many number
of outbound connections for sending commands.
.br
Default: \fI10\fP
.TP
\fBsubmit_command\fP
Default: \fI/usr/bin/php /usr/share/gromox/submit.php\fP
.TP
\fBuser_cache_interval\fP
Sets the time how long the MAPI profile is cached before it is written to disk.
.br
Default: \fI1 hour\fP
.TP
\fBuser_table_size\fP
Default: \fI5000\fP
.TP
\fBx500_org_name\fP
Default: (unspecified)
.TP
\fBzcore_listen\fP
The named path for the AF_LOCAL socket that zcore will listen on.
.br
Default: \fI/run/gromox/zcore.sock\fP
.TP
\fBzcore_log_file\fP
Target for log messages here. Special values: "\fI-\fP" (stderr/syslog
depending on parent PID) or "\fIsyslog\fP" are recognized.
.br
Default: \fI-\fP (auto)
.TP
\fBzcore_log_level\fP
Maximum verbosity of logging. 1=crit, 2=error, 3=warn, 4=notice, 5=info, 6=debug.
.br
Default: \fI4\fP (notice)
.TP
\fBzcore_max_obh_per_session\fP
The maximum number of object handles each session can have at any one time
(e.g. folders/messages/etc. open simultaneously). Use 0 to indicate unlimited.
There is one session for each time a mailbox is opened.
.br
Default: \fI500\fP
.TP
\fBzcore_threads_num\fP
The minimum number of client processing threads to keep around.
.br
Default: \fI10\fP
.TP
\fBzrpc_debug\fP
Log every incoming zcore RPC and the return code of the operation in a minimal
fashion to stdout. Level 1 emits RPCs with a failure return code, level 2 emits
all RPCs. Note the daemon log level needs to be "debug" (6), too.
.br
Default: \fI0\fP
.SH Network protocol
The transmissions on the zcore socket are simple concatenations of protocol
data units built using the NDR format. The PDU length is present within the PDU
itself near the start.
.PP
.in +4n
.EX
{
	leuint32_t length;
	char pdu[];
}
.EE
.in
.PP
.in +4n
.EX
pdu := {
	uint8_t call_id;
	string directory;
	switch (call_id) {
		...
	}
}
.SH Store lookup
zcore determines the store path for a user from the user database, which is
provided by mysql_adaptor(4gx).
.PP
The filemap that specifies how paths are handled is located at
\fIdata_file_path\fP/exmdb_list.txt, whereby data_file_path is the eponymous
directive from the config file.
.PP
Each line in this file consists of 4 columns separated by whitespace:
.IP \(bu 4
A portion of the store path to match on
.IP \(bu 4
The type of store ("private" or "public")
.IP \(bu 4
The IPv6 socket address of the server running exmdb_provider(4gx). The address
must conform to gromox(7) \sc "Host addresses".
.IP \(bu 4
The TCP port number of the server
.SH Files
.IP \(bu 4
\fIconfig_file_path\fP/exmdb_list.txt: exmdb multiserver selection map, see
exmdb_provider(4gx) for details.
.IP \(bu 4
\fIdata_file_path\fP/folder_names.txt: Translations for essential folders in a
message store.
.IP \(bu 4
\fIdata_file_path\fP/notify_bounce/: templates for read/nonread notification
mails sent to originators
.SH Notes
Behavior for the address book generally mirrors exchange_nsp(4gx), so see that
manpage for additional notes.
.SH See also
\fBgromox\fP(7)
